Problem

Literal colon routes (e.g., /api:v1) currently fail when using:

• engine.Handler()
• Direct http.Handler usage (e.g., &http.Server{Handler: engine})

They only work when using engine.Run()

Related

• Fixes Literal colon routes don't work properly in non-Run() scenarios #4413
• Related to PR feat(router): add literal colon support (#1432) #2857 (original literal colon implementation)

Reproduction

package main

import (
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()

	r.GET(`/api\:v1`, func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "literal colon works!"})
	})

	r.GET("/api/:version", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"version": c.Param("version")})
	})

	server := &http.Server{
		Addr:    ":8080",
		Handler: r,
	}

	log.Println("Server starting on :8080")
	log.Println("Test literal colon: curl http://localhost:8080/api:v1")
	log.Println("Test param route: curl http://localhost:8080/api/v2")

	if err := server.ListenAndServe(); err != nil {
		log.Fatal(err)
	}
}

Output Before Fix

Root Cause

The updateRouteTrees() method converts escaped paths (/api\:v1) to actual colon paths (/api:v1), but it's only called inside engine.Run(). Other usage patterns never trigger this conversion.

Fixes #4413

Solution

Add a sync.Once mechanism in ServeHTTP() to ensure updateRouteTrees() is called exactly once before processing the first request, regardless of how the engine is used.

Changes

Modified Files:

• gin.go: Added routeTreesUpdated sync.Once field to Engine struct.
• gin.go: Updated ServeHTTP() to call updateRouteTrees() once on first request.

Testing

1. Literal colon routes with engine.Run()
2. Literal colon routes with engine.Handler()
3. Literal colon routes with direct ServeHTTP() usage
4. Mixed routes (static, param, and literal colon) work together
5. updateRouteTrees() is called only once across multiple requests

Output after the Fix:

Result: Request to /api:v1 now returns 200 OK with the correct response!

Breaking Changes

None. This is a pure bug fix with no API changes.

Pull Request Checklist

Please ensure your pull request meets the following requirements:

• Open your pull request against the master branch.
• All tests pass in available continuous integration systems (e.g., GitHub Actions).
• Tests are added or modified as needed to cover code changes.

Thank you for contributing!